What is Clam
What is Clam?

Morello Clam lets you automate Win95/NT:

•	Automate those tedious chores.

•	Add repeatability to important procedures.

•	Do it quickly and easily with Clam’s visual editor.

With Morello Clam you can:

•	Perform simple or complex operations on groups of files or folders.

•	Automatically perform sequences of actions.

•	Control other applications.

Visual editing means that there is no complicated language syntax to remember - everything is controlled by friendly dialog boxes.

Read getting started  for more information.


Getting Started

You do not need any experience of programming to use Clam. Even if you are an experienced programmer, it is still worth looking through this help file, because Clam is quite different to most conventional scripting languages.

Carry on with this browse sequence to learn the basic concepts and techniques used to program Clam.

Or, if you want a more practical introduction, look at the tutorial section.

Finally, when you have mastered the basics, you will want to look at the reference sections to find out specific informartion about commands, user and system variables, and conditionals.


Using Clam Script Files

Clam allows you to work on just one script at a time. Clam script files usually take the extension .clm (eg MyScript.clm). Clam supports the standard File menu commands:

New		Create a new Clam script file.
Open		Open an existing Clam script file.
Save		Save the current Clam script file.
Save As		Save the current Clam script file using a different name.
You can also use the standard toolbar buttons shown to create, open and close scripts.


Adding Commands to a Script

To add a command to a simple script:

1	Make sure that you are in Insert After mode. The status bar should show INS AFTER (not INS_BEFORE or INS_INTO). If not, choose the Insert|After menu item.
2	Choose where in the script you want the new command to be inserted. In the main window, select the item (if the script is empty, select the Script item).
3	Choose the type of command you want to insert, using the Insert|New Command menu.
4	Fill out the values for the new command, in the dialog which appears.

The Commands toolbar has a button for each type of command, and you can use this instead of the menu. For a description of each available command see the List of Commands.

For more complex scripts, for example if you are using loops and other constructs, you will need to set the insert mode as follows. Either use the Insert menu, or the toolbar buttons:

Insert After		Inserts the next command after the selected command.
Insert Before		Inserts the next command before the selected command.
Insert Into		Inserts the next command into the selected command - only applies to control structures such as loops.


Editing Commands in a Script

To edit a command in a script:

1.	Select the command in the main window.

1.	Choose Edit|Command Properties from the menu, or use the toolbar button:

Alternatively, you can double click the command.

This will bring up the dialog associated with the command, to allow you to edit its properties.


Deleting Commands from a Script

To delete a command from a script:

1.	Select the command in the main window.

1.	Choose Edit|Delete Command from the menu, use the Del key, or use the toolbar button:


Editing a Script

You can edit elements in a script using the standard Edit menu commands Cut, Copy and Paste.

If you select a command which has sub-command (such as a loop or an if command), cut or copy will apply to the sub-command as well.

When you paste the contents of the clipboard, they will be inserted before, after or into the current command, depending on the insert mode.


Running a Script

You can run a script directly from within Clam. You must first open the script. Then choose File|Run from the menu, or use the toolbar button:


Using Variables

You can use variables to store information temporarily, while the script is running. Variables always hold text data, but in some cases you can use that text to represent something else (such as a number, or a filename etc).

You can have as many variables as you like in your script, and you can give them whatever names you like (subject to a few restrictions). Variables are created automatically when they are first used.

You can set the value of a variable using an Assign Command. You can then use that variable almost anywhere you might normally use a text value. Simply enclose the variable in [square brackets].

For example, you can use an Assign Command to create a variable called MyName, and set its value to Joe Bloggs. You could then use an Alert Command to display the following message in a window:

My name is [MyName].

When the script runs, what is actually displayed will be:

My Name is Joe Bloggs.

System Variables

In addition to normal user variables, there are some predifined system variables. These variables contain special values - for example the system variable called :date will always have the current date as its value.

You cannot assign a value to these variables.

For a complete list see system variables.


The easy way to add Variables

Variables can be added to most edit fields, including anywhere a filename, message or other piece of information is to be used.

The easiest way to insert a variable is to right click over the edit field. This will bring up a list of all currently known variables. Select any one, and it will be inserted into the edit field at the current cursor position, complete with the necessary brackets [].

Of course, if you wish, you can type the variable name in manually instead.


Programming Constructs

In some cases, the operation of a script is very simple - it just mechanically performs a series of steps, one after another. In other cases, however, a slightly more complex program structure is required. There are two examples of this in Clam - iteration (looping), and conditional execution (if commands).

Iteration

Clam allows you to repeat the same sequence of operations again and again - this is called iteration (or looping). For example, if you wanted a little program to make a copy of all the *.txt files in your working directory, you would use a loop:

In this case, the script first puts up an alert box (to tell the user that the backup is about to start). Then it executes the loop command for all txt files in the work directory - this means that the copy command is executed for each file which is present.

Finally, the second alert box is displayed, once only, to indicate that the operation is finished.

Notice how the command(s) which are part of the loop are included as a branch off the loop command. In order to add a command to this branch, you must be in Insert Into mode (selected from the Edit menu).

Conditional Execution

An If command has a branch, just like loop commands. The If command tests a particular condition and only executes the commands in the branch if the condition is true.

Nesting

Loops and conditional branches can contain other loops and conditional branches, leading to nested tree structures, see the examples.


List of Examples

To get you started, the following examples and explanations are included with Clam:

HelloWorld.clm	The simplest possible script!
Variables.clm	Demonstrates the use of User and System Variables.
Loop.clm	Demonstrates iteration and basic program structure.
DoubleLoop.clm	Demonstratesnexted iteration.


Hello World Example

Here is a script which is about as simple as is possible. All it does is to put up an information window which says “Hello World”!

Start Clam and create a new script (use Edit|New, or the toolbar button).

Insert a new Alert Command (use Insert|New Command|Alert, or the Alert toolbar button). the following dialog will appear, and you should fill it in as shown:

That’s all! The script is complete, and should look like this:

Now all you need to do is run the script, using File|Run, or the GO toolbar button. The script will run, and display a window like this:

If you don’t want to create this script yourself, you can find it in HelloWorld.clm in the Clam install folder.


Variables Example

This script uses variables in a few different ways. You can find the script in Variables.clm in the install folder. Open it, try it out, read the description, and then experiment with it! It should look like this:

To look at any command in more detail, select it an the choose Edit|Command Properties (or hit Enter), to bring up its properties window.

The first command creates a variable called message and gives it a value of Hello World. From that point on, whenever you include [message] in any expression, the value Hello World will be substituted when the program runs.

Command 2, an Alert, demonstrates this. If you inspect its properties you will see that the message is set to “message contains [message]”, but what it actually displays is:

message contains Hello World

Command 3 illustrates the system variable date:, which always returns the current date. Command 4 changes the value of message, to “The time is [:time]”. This demostrates that, of course, you can use variables when setting the value of another variable. Command 5 displays the new value of message.


Loop Example

This example uses a loop. The purpose of the script is to list all the contents of a particular folder, and to store result in a text file:

The program writes an initial message to the log file, to say which folder it is scanning. It then loops over every file in that folder, and writes a message to the log. Then it writes out a final mesage to the log.

Use of variables

Notice how we use variables - folder holds the name of the folder we want to scan, logfile holds the name of the log file. Why do we use variables? It makes the program easier to update in the future. For example, if we need to change the program to put its results in a different file, we simply edit the Assign command for logfile and change the name of the file. If we didn’t use a variable, the file name c:\clamlog.txt would appear in several places in the script - it would take longer to change, and we might miss some of them.

Controlling the log file

Notice that we use Add Newline when writing to file, to ensure that each message comes out on a separate line. Notice also that the first message has Append switched off - this forces it to generate a new file, whether or not the file already exists. Each time the program runs, the previous file is deleted.

The other writes have append switched on, so that they add data to the file without deleting it.


Nexted Loop Example
Nested Loop Example

This example uses a 2 loops. The script demonstrates a very simple backup program, which you could run regularly to back up your working area. What the script does is to copy all your working files from your work folder to your backup folder:

First we set up variables to hold our source (work) area and our backup area. You could set these up to more realistic values if you wanted to adapt this script for your own use. For example, you might place the backup folder on a floppy disk!

The particular files we work with (for this example) are doc files, bmp files and txt files. We want to copy all files of these types, but not any other types (our working folder might have lots of other junk, which we don’t want to backup).

To do this, we use a List Loop command - examine it, we have set it up to hold 3 items, *.doc, *.bmp and *.txt, our 3 types of file.

The list loop runs once for each value in the list, with variable type set to current value. within this loop we have a second loop which executes for all files which match type, and copies the files it finds. On the first pass through, all the *.doc files are copied, then next time all the *.bmp files are copies, etc.

The nice thing about the list loop is that if you wanted to add more types of file to the backup, you simply need to add them to the list.


List of Commands

This is a list of commands by category. Refer to the Contents page for an alphabetical list of commands.

System Commands

	File Action - perform an operation (such as Copy or Delete) on a file or folder.
	Run - run an executable program.

Control

	Assign - assign a value to a variable.
	File Loop - perform operations on a group of files.
	List Loop - repeat operations for a list of parameters.
	If - perform operations conditionally.
	Exit - terminate the script immediately.

Logging and User Messages

	Alert - display an error, warning or information dialog to the user.
	Write to File - write data to a file.

System Information

	File Information - obtain information about a file, such as it size, attributes, etc.


Alert Commands
Alert Command

An Alert Command allows you to display a message to the user in a message box. The user must dismiss the message box before execution of the script continues.

Add an Alert to a script using the Insert|New Command|Alert menu, or using the Alert toolbar button:

The following dialog appears:

Title	The title of the message box.
Message	The actual message which appears in the message box.
Type of Icon	Controls the icon which appears in the message box, to represent information, a warning, a query, or an error.
Buttons available	Controls the buttons displayed on the message box.
Return variable	The name of a new or existing User Variable which will hold the name of the button selected by the user. When the message box is closed, this will hold the name of the button the user pressed (“OK”, “Cancel” etc). If you do nat want to know which button the user pressed, you need not enter a name in this field.
AutoCancel	If this is checked, the script will abort if the user selects the Cancel button in the message box. If this is not checked, Cancel will have no special action - the Return variable will simply be set to “Cancel”.


Assign Command

An Assign Command assigns a value to a user variable.

Add an Assign to a script using the Insert|New Command|Assign menu, or using the Assign toolbar button.

The following dialog appears.

Value	The new value of the variable.
Variable	The name of a new or existing User Variable which will be set to the new value.


Exit Command

An ExitCommand terminates a script immediately, so that any subsequent commands are not carried out. This is commonly used in conjunction with an If Command to stop a script if an error is detected, etc.

Add an Exit to a script using the Insert|New Command|Exit menu, or using the Exit toolbar button. See the note on program constructs for more information.

The following dialog appears. There are no parameters for an exit command.


File Action Command

A File Action Command allows you to perform various functions on files, such as copying or deleting files.

Add a File Action to a script using the Insert|New Command|File Action menu, or using the File Action toolbar button:

The following dialog appears:

Action	The action to be performed on the file (copy, delete etc.), see below.
Source File	The primary or source file for the operation.
Destination File	The destination file for copy, append and move actions.
Attributes	Determines the file attributes for the Set Attributes action.

File actions are

Copy	Copy the source file to the destination, leaving the source file unchanged.
Append To	Append the source file to the end of the destination file. It the destination file does not already exist, create it.
Move	Same as Copy, but the source file is deleted. This has the effect of renaming the source file.
Delete	Deletes the source file.
Touch	Sets the last access time of the file to the current time. If the file does not exist already, a new empty file is created.
Set Attributes	Sets the source file Read Only, Archive, Hidden and System attributes.
Create Folder	Creates a new folder with the source file name. The parent folder must exist already.
Delete Folder	Deletes the source file folder. The folder must be empty.


File Information Command

A File Information Command allows you to get information about a file. The information is stored in a User Variable of your choice.

Add a File Info command to a script using the Insert|New Command|File Info menu, or using the File Info toolbar button.

The following dialog appears:

File name	The name of the file which you want to find information about.
Type of Information	You can obtain various pieces of information about a file, such as its size, the last time it was accessed, etc. These are listed below.
Date Time Date and Time	If the type of information requested is time related (for example, the creation time of a file), you can choose how to extract this information - date only, time only, or both.
Variable	This is the name of a User Variable where the information will be stored,

Information Type is one of the following:

Access Time	The time the file was last accessed.
Archive Attribute	Archive attribute. This is set whenever the file is updated.
Creation Time	The time the file was originally created.
Existance	True if the file exists.
Hidden Attribute	True if the file is hidden.
Modified Time	The time the file was last modified.
ReadOnly Attribute	True if the file is read only.
Size	The size of the file in bytes.
System Attribute	True if this is a system file.


File Loop Command

A File Loop Command allows you to perform a repeated set of actions on a group of files. You can choose to act on all the files in a particular folder, or just particular files in the folder. You can also choose to apply the same actions to all subfolders within the selected folder.

Add a File Loop to a script using the Insert|New Command|File Loop menu, or using the File Loop toolbar button. See the note on program constructs for more information.

The following dialog appears:

Folder	This is the name of the folder where the file search will take place. Leave this blank to indicate the current working directory.
Include Subfolders	If this is checked, the same search will be carried out not just in the specified folder, but also in all of its subfolders (and all of their subfolders, etc. etc...)
File Name	This specifies which files will be involved in the loop. You can include wildcard characters * and ? in the file spec. E.g. *.txt will loop over all Text files, etc. Leave this blank to search all files.
Loop Variable	This is the name of a User Variable which will hold the full name of the file on each pass throgh the loop.


If Command

An If Command allows you execute commands conditionally. The commands within the If will only be executed if the condition specified in the command is true.

Add an If to a script using the Insert|New Command|If menu, or using the If toolbar button. See the note on program constructs for more information.

The following dialog appears:

Change	Opens a Set Condition dialog which allows you to set the condition for the If command.


List Loop Command

A List Loop Command allows you to repeat set of actions for a list of values.

Add a List Loop to a script using the Insert|New Command|List Loop menu, or using the List Loop toolbar button. See the note on program constructs for more information.

The following dialog appears:

Loop Variable	This is the name of a User Variable which will hold the value on each pass through the loop.
List	Enter the list of values for the loop, one per line. The loop will execute once for each value.


Runommand
Run Command

A Run Command allows you execute other programs from within your script.

Add a Run to a script using the Insert|New Command|Run menu, or using the Run toolbar button.

The following dialog appears:

Application to run	The full command line for the program to be executed
Continue script immediately	If checked, the script will carry on, leaving the new application running separately.
Wait until program completes	If checked, the script will halt until the called program terminates.
Store Exit Code	A User Variable where the exit code returned should be stored. This is only valid if Wait is checked.


Write to File Command

A Write to File Command allows you to write information to a file.

Add a Write to File to a script using the Insert|New Command|Write to File menu, or using the Write to File toolbar button:

The following dialog appears:

File	The name of the file to write to.
Always create a new file	If this box is checked, a new file will always be created. Any existing file with the same name will be deleted.
Append to existing file	If this box is checked, data will be appended to the end of any existing file of the same name. If the file does not already exist, a new file will be created.
Message	The text to be written to the file.
Add Newline	If this is checked, a newline will be added to the end of the message.


User Variables

For general information about variables, see Using Variables.

You can have as many different user variables as you wish, and you can choose whatever names you like, made up of letters, numbers, punctuation and space characters. The only restrictions are:

•	The name must be less that 256 characters long.

•	You cannot use square brackets or colon characters in variable names (‘[‘, ‘]’ or ‘:’).

For example, the following are all valid:

X

My Variable

Result-3

Names are case sensitive, so count, Count and COUNT would all be treated as different variables.


System Variables

For general information about variables, see Using Variables.

System variables are predefined. The names start with a colon ‘:’ character, to distinguish them from User Variables. The following variables are available:

:currentfolder	The current working folder.
:date	The current date.
:lasterror	A string which indicates the most recent system error (such as a file access error) to have occurred while using Clam.
:lasterrorno	An integer indicating the number of the :lasterror message.
:systemfolder	The system folder.
:tempfolder	The folder allocated for temporary files.
:time	The current time.
:windowsfolder	The windows folder.


Using Conditions

If commands use the Set Condition dialog to determine the conditions under which it will execute the commands in its branch:

To determine if the condition is true, Clam evaluates Expression1, interprets it in a particular way, and then tests it. For example, if we interpret Expression1 as a text string, we can test to see if it is blank.

Some tests are comparitive, in which case a second expression (Expression 2) can be involved. For example, if both expression 1 and 2 are interpreted as integers, you can test if they are equal.

All possible conditions are listed below.

Interpreting Expression1 as a String

Condition	Expr2	Comment
IsBlank	Not used	True if Expr1 is an empty string
Equals	String	True if Expr1 and Expr2 are identical

Interpreting Expression1 as an Integer

Condition	Expr2	Comment
Equals	Integer	True if Expr1 and Expr2 are equal numbers
Does Not Equal	Integer	True if Expr1 and Expr2 are not equal numbers
Is Less Than Is Greater Than Is Less Than or Equal Is Greater Than or Equal	Integer	True if the condition is met.


Licence

Shareware

The shareware version is supplied with absolutely no warranty, and is used entirely at your own risk. You may use it for evaluation purposes only, free of charge for a maximum of 30 days. You may also distribute it freely to others under the conditions described under Registration.

Registered Licence

Upon our acceptance of your registration fee, the following terms apply:

You will receive a password which removes the specific shareware restrictions stated under Registration.

You accept responsibility to make all reasonable efforts to ensure that the password does not become known to others.

You are permitted to use the licenced copy on a single machine or network, provided only one person can use the program at any time.

The program is supplied without warranty.

We do not guarantee the continuous availability of this software via the Internet, or any other source. Please ensure that your shareware copy is adequately backed up before you register.

In any event our liability is limited to the fee you paid for the software.


Registration

Morello Clam is shareware. This means that you are free to use it for evaluation purposes for up to 30 days after you first install it. If you wish to continue using it after this period, you must register.

The purpose of shareware is to allow you to evaluate the product before paying for it. In order for the development of Clam to continue, we rely on the honesty of our users. To encourage registration, the unregistered version is has a deliberate limitation which is removed when you register - you cannot save your scripts with the unregistered version.

You are permitted (and encouraged) to distribute the unregistered version of this program freely to others, via any means such as the Internet or CD-ROM provided it is complete and unmodified, including all help files and copyright notices, and that you do not claim to own it, and that you do not charge for it other than a reasonable fee to cover distribution costs. You do not need our permission, but please drop us an email so that we can add you to our mailing list.

You are not allowed to distribute the personal password you will receive as a result of registering.

What you get when you register...

When you register, you receive the right to continue using the copy of Morello Clam which you already have, under the terms of the Licence.

You will also receive a password which restores the full functionality of the software (removing the shareware limitations stated above). This password is confidential between yourself and Morello, and in registering you agree to take reasonable steps to keep the password confidential.

Note that we do not supply you with a disk copy of the program. This is available for an extra charge, although most users prefer to download the latest version from our website. We recommend that you store 2 backup copies (at least) of the version you have registered, and of course keep your password somewhere safe.

Payment

Anywhere in the world: 15 UK Pounds, payable by cheque, Postal Order or Money Order.

US Only: 25 US Dollars, by cheque ONLY

Non-US: if you find difficulty in paying in UK Pounds, please contact us for the price in your local currency.

Please DO NOT make payments in US Dollars from non-US banks, we cannot accept them.

If you require a copy of the program on diskette, please add an extra 3 pounds (or 5 dollars) to the amount, to cover our costs.

In addition to your payment, please also tell us:

•	Your full name and address (needed for registration)

•	Your email address (if you wish to receive your password as quickly as possible)

•	The version of Morello Clam you wish to register.